Java: The Good Parts by Jim Waldo

Author:Jim Waldo
Language: eng
Format: epub, pdf
Tags: COMPUTERS / Programming Languages / Java
ISBN: 9781449382339
Publisher: O’Reilly Media
Published: 2010-04-19T16:00:00+00:00

Package Documentation

We’ve taken a look at how to use Javadoc to document interfaces and implementations. This generates a lot of useful documentation when used correctly, and the nice thing about the documentation is that it is colocated with the code that it is describing, making it that much harder to change one without changing the other. Of course, programmers in a hurry (or those who hate to write anything that isn’t compiled) will still avoid writing documentation, or revising it when needed, but javadoc makes it more convenient to do the right thing and make sure that changes in the code get described in the documentation.

If this were all that javadoc did, it would be a good thing. Indeed, this is all that most programmers use javadoc to do. But there is a missing piece of the documentation if all that is described are the interfaces and classes. What hasn’t been shown yet is how all of those pieces are meant to fit together to form a system. This is the architecture of the system, and it provides a framework for the reader of the documentation to put the pieces into place and see the system as a system. Although the individual class and interface entries may tell the reader how the pieces function individually, it is this broader documentation that tells the reader the structure that unifies those pieces.

Javadoc supplies a mechanism for this kind of architectural documentation, which is (unfortunately) often either unknown, ignored, or abused. This mechanism is the package comment file, which I mentioned earlier in this chapter. In any package, you can include a file that can be used to specify the architectural documentation for the package. Prior to JDK 5.0, this file was named package.html, and was a standard HTML file that could contain documentation about the package. Since JDK 5.0, this file can be a java source file containing the package declaration, package annotations, and the documentation (including all of the standard javadoc tags).

Such comment files need not be huge. For example, a reasonable comment for our statistics package might look something like:

Download

Copyright Disclaimer:
This site does not store any files on its server. We only index and link to content provided by other sites. Please contact the content providers to delete copyright contents if any and email us, we'll remove relevant links or contents immediately.